Netware Super Library/Netware Super Library.iso/pegamail/pdpmpop/pmpop.txt

Text File | 1994-07-04 | 18KB | 351 lines

┌──────────────────────────────────────────────────────────────────────┐
│           PMPOP - a POP3/SMTP e-mail transport subsystem             │
│                 for use with Pegasus Mail/DOS v3.1                   │
│     Copyright (c) 1990-94, David Harris, all rights reserved.        │
└──────────────────────────────────────────────────────────────────────┘

─── What is PMPOP? ───────────────────────────────────

PMPOP is an add-on transport for the Pegasus Mail electronic mail system
which provides access to the Internet-based POP3 and SMTP mail protocols
for those users running either Novell's LAN Workplace for DOS TCP/IP
suite, or those using Packet Drivers to access their ethernet card.
PMPOP appears to the user to be a part of Pegasus Mail, and is accessed
via submenu choices added to the Pegasus Mail main menu. While PMPOP
will run perfectly happily in the Novell NetWare environment, its most
likely users will be those who are not using NetWare but want to use
Pegasus Mail to send and receive Internet electronic mail.

POP3 ("Post Office Protocol version 3") is an Internet standard for
retrieving mail received and stored on your behalf by another host. The
protocol is necessary because your PC may not always be turned on, or
running the program necessary to receive mail, so it's more appropriate
to ask a larger machine which IS available all the time to receive it
for you. POP3 is a receive-only protocol - it makes no provision for
sending mail. PMPOP implements the POP3 protocol as described in the
Internet standards document RFC1225.

SMTP ("Simple Mail Transfer Protocol") is the traditional Internet
standard for transmission of electronic mail. PMPOP implements an "SMTP
client", or that half of the SMTP protocol which is concerned with
sending mail. Because PMPOP receives mail using the POP3 protocol, it
does not have to implement the receiving half of SMTP, which is very
complicated on a simple, single-task system like MS-DOS. The SMTP
protocol is described in the Internet standards documents RFC821 and
RFC1123.

Thus, by implementing POP3 to receive mail and SMTP to send it, PMPOP
provides a complete TCP/IP-based mail solution which you can run on a PC
running MS-DOS.


─── Who might use PMPOP? ─────────────────────────────

If you have a TCP/IP network with Unix hosts, or a connection to the
world-wide Internet, you may want to use PMPOP. The services provided by
PMPOP can usually be more completely and robustly performed by a native
SMTP implementation, so if you are running under NetWare, you might be
better advised to consider using either the Mercury Mail Transport
System (from the same author as PMPOP and Pegasus Mail), or the Charon
SMTP gateway from Clarkson University. Both of these are native, robust
SMTP implementations specifically intended for use in the NetWare
environment.

If you do not use NetWare, are not able to connect to a NetWare server,
or if you simply prefer to use the POP3/SMTP protocols to send e-mail
directly from your PC, then PMPOP is probably of interest to you.


─── System requirements ──────────────────────────────

To use PMPOP, you must have the following:

   *  An IBM PC, XT, AT or 100% compatible computer
   *  MS-DOS or PC-DOS version 3.0 or later
   *  At least 512KB conventional RAM available after DOS is loaded
   *  Either:
      - The LAN Workplace for DOS TCP/IP stack version 4.1 or later
      - A valid, properly installed Type 1 Packet Driver
   *  Pegasus Mail/DOS version 3.1 or later
      - PMPOP can be used with Pegasus Mail v3.0, but doing so requires
      - some changes: see the section later in this file for details.
   *  Permission from your TCP/IP network manager to run your PC on
      the IP network, and an appropriate IP address.


─── Before installation ──────────────────────────────

Before you install PMPOP on your system, take a moment to find out the
following information. Record it on a piece of paper and keep the paper
in front of you as you install PMPOP. The person who manages your TCP/IP
network, or the system manager of a Unix machine on your TCP/IP network
should both be able to provide you with this information.

A: Your IP address    ___.___.___.___   (ask your IP network manager)

B: Your IP netmask    255.___.___.___   (ask your IP network manager)

C: The name of the host from which you intend to retrieve mail using
   the POP3 protocol; you must have a valid account with a current
   password on this host (ask your IP network manager if you are unsure
   about this)

   POP3 mail host:  __________________________________

   Your user ID on the POP3 host:  ___________________

   The password for your user ID:  ___________________

D: The name of a machine on your IP network which can transmit mail on
   your behalf. This machine must be running a full SMTP implementation
   and you must have the permission of its system manager before you
   attempt to use it. In practically every instance you can use the
   same machine from which you retrieve mail (see C: above), but if you
   are unsure, check it out first.

   SMTP mail host:  __________________________________


─── Installing PMPOP on your system ──────────────────

PMPOP is provided in two versions - LWPMPOP.EXE, which you should use if
you run Novell's LAN Workplace TCP/IP protocol stack on your machine, and
PDPMPOP.EXE, which you should use if you use Packet Drivers.

Step 1:  Choose the correct version of PMPOP for your system, make a copy
         of it to a location somewhere on your DOS path, and rename the
         copy to PMPOP.EXE. The remaining steps in the installation apply
         equally to either version except where noted specifically, and
         assume that PMPOP is called PMPOP.EXE. PMPOP can be run from a
         public directory on a file server if you wish.

Step 2:  Copy the files PMGATE.SYS and PM-MENU.RSC supplied with PMPOP
         into the same directory as the copy of Pegasus Mail which you
         intend to use.

         *** NOTE: if you are already using other user-defined gateways
         for Pegasus Mail, you will have to use PCONFIG to duplicate the
         definition in PMPOP's PMGATE.SYS file instead of overwriting
         your current file. The correct settings for the gateway
         definition screen in PCONFIG are shown in the appendix at the
         end of this file. Similarly, if you already have additions to
         your Pegasus Mail menus using a PM-MENU.RSC file, you will have
         to modify them to add the options shown in the PM-MENU.R file
         supplied with PMPOP.

Step 2a: If you are using the Packet driver version of PMPOP, copy the
         file WATTCP.CFG to the same directory as PMPOP.EXE and modify
         its contents to be correct for your network system. The values
         in WATTCP.CFG are discussed at the end of this file. You do not
         need this file if you use the LAN Workplace version of PMPOP.

Step 3:  Run Pegasus Mail, and choose "Check for new mail" from the main
         menu. A pop-up menu should appear with three options (or more if
         you already had options there). Choose "Configure PMPOP" from
         the submenu, and PMPOP's configuration window should appear. In
         the field marked "Get Mail From", enter the name in part C of
         your preinstallation data sheet. In the "User name" and "User
         password" sections, enter the user id and its password for the
         account you wish to access on the mail host. In the field
         marked "SMTP Mail host", enter the name from part D of your
         preinstallation data sheet. Press <Ctrl-Enter> to save the
         values you have entered.

That's all that's required. Now, whenever you want to check the POP3 mail
host for new mail, all you have to do is select "Get new mail by POP3"
and PMPOP will be automatically invoked to download your new mail.
Similarly, when you have composed messages and wish to send them, select
"Send all messages" from the "Send a message" submenu and all messages
composed since the last time you ran PMPOP to send mail will be sent.


─── Modifying WATTCP.CFG for your system ─────────────

If you are using the Packet Driver version of PMPOP, then you must modify
the file WATTCP.CFG to describe your machine. WATTCP.CFG can be placed in
the same directory as PMPOP.EXE, or if you need to locate it somewhere
else, you can create a DOS environment variable called WATTCP.CFG which
points to the directory where it is located - for example:

    set WATTCP.CFG=C:\DOS

If you already use another program which uses Erick Engelke's WATTCP
TCP/IP libraries, you can use the same WATTCP.CFG file it uses for PMPOP
as well.

WATTCP.CFG is a simple text file which provides the WATTCP TCP/IP stack
with the basic information it needs to connect to your TCP/IP network.
A sample WATTCP.CFG file might look like this:

      my_ip=129.97.176.99
      netmask=255.255.0.0           # Netmask for the Interface
      nameserver=129.97.128.24      # Default nameserver to use
      nameserver=129.97.128.196     # Alternate nameserver
      gateway=129.97.176.1          # IP routing gateway
      domainslist="uwaterloo.ca"

Any text appearing after a '#' on a line is regarded as a comment and is
ignored. Trailing whitespace on a line is also ignored. The fields in the
WATTCP.CFG file are as follows:

   MY_IP: should specify the numeric IP address of your PC. You should
   use the value from part A of your preinstallation sheet here.

   NETMASK: must specify the proper IP subnet mask used on your
   network. If you do NOT know this value, then do NOT use PDPMPOP
   without getting the correct value from your IP network manager. You
   should use the value from part B of your preinstallation sheet here.

   NAMESERVER: should contain the numeric IP address to a machine
   (usually a unix machine) which provides name resolution services on
   your IP network. Your IP network manager will be able to tell you the
   address of a nameserver on your TCP/IP network.

   GATEWAY: should contain the numeric IP address of a machine which
   can route IP packets on your behalf. Your IP network manager will
   be able to tell you the address of a router on your TCP/IP network.

   DOMAINSLIST: is an optional field which can contain a list of
   comma-separated domain names which WATTCP will try using when
   resolving addresses with no domain part.


─── Correct gateway definition values for PMPOP ──────

If you already have user-defined gateway definitions in your copy of
Pegasus Mail, then you cannot simply copy the PMGATE.SYS file supplied
with PMPOP into your PMAIL.EXE directory, since doing so will overwrite
your current definitions. Instead, you must either import the definition,
or create a new one in your existing definition file. In either case, you
have to use the Pegasus Mail configuration utility, PCONFIG.EXE, to do
this.

If you are using PCONFIG v3.1, then you can import the definition from
the file provided with PMPOP. Run PCONFIG, and choose "Manage user-
defined gateways" from the main menu. Your gateway list will appear;
press <F10> to import the definition contained in the file provided with
PMPOP. PCONFIG will ask you to enter a filename - give the full path to
the copy of PMGATE.SYS provided with PMPOP. When you press <Enter>,
PCONFIG will import the gateway definition contained in the PMPOP file
into your current gateway list. You need do nothing more at this point
except save and exit.

If you are using an older version of PCONFIG, you must create the
definition from scratch in your definition list. Press <Ins> to create a
new definition, and give it the name PMPOP. Fill in the definition screen
exactly as shown below:

   ╔══════════════════ User Gateway Definition ══════════════════╗
   ║                                                             ║
   ║              Gateway name : [PMPOP           ]              ║
   ║            *New mail path :                                 ║
   ║    Is  a program to run? :  N                              ║
   ║     *New mail search mask :                                 ║
   ║       *Outgoing mail path :  ~h                             ║
   ║    *Run for outgoing mail :                                 ║
   ║          *Filename format :  ~d~d.MSG                       ║
   ║   Run to validate address :                                 ║
   ║     *Reply address format :  "~p" <~n>                      ║
   ║   Accepts SMTP addresses? :  Y                              ║
   ║   Simple message headers? :  'Glue' headers                 ║
   ║     UUEncode attachments? :  Y                              ║
   ║           Burst messages? :  N                              ║
   ║       Strip gateway name? :  Y                              ║
   ║   Force all mail through? :  N                              ║
   ║                                                             ║
   ╚═════════════════════════════════════════════════════════════╝


─── Using PMPOP with Pegasus Mail 3.0 ────────────────

PMPOP can be used with Pegasus Mail version 3.0, but doing so requires
one extra installation step. You must edit the file PM-MENU.R supplied
with PMPOP using a text editor (such as David's Text Editor, or if the
worst comes to the worst, the DOS EDIT command). Locate the line in the
file which looks like this:

   "pmpop -3~w -v2 -g > nul"

You must replace the '~w' in this string with the full path to the
location where your new mail is stored. In the NetWare environment, this
will be whatever is the name of your directory in SYS:MAIL; in other
environments, it will be whatever value you told Pegasus Mail to use when
you installed it for standalone operation. As an example, say you are
running in standalone mode and your new mail folder is C:\MAIL\DAVID:
you would change this line to read:

   "pmpop -3C:\\MAIL\\DAVID -v2 -g > nul"

Notice the way the backslash characters are doubled - this is necessary
to prevent the resource compiler from interpreting them as escape
characters.

Once you have made this change, save the file, and issue the command:

     RESCOM pm-menu.r

This invokes the Pegasus Mail resource compiler, ResCom, to prepare a new
PM-MENU.RSC file. Once you have created the new PM-MENU.RSC file, you
should follow all the steps shown above, using the new PM-MENU.RSC file
instead of the shipped version wherever specified.

For advanced users: you can also use any other valid substitution in this
string; so if you have set up Pegasus Mail for several users on your
system and have defined the new mail folder as C:\MAIL\~8 in Pegasus
Mail, you can do the same thing in this string.


─── Command-line Options Summary ─────────────────────

PMPOP supports the following command-line switches (you can use either '/'
or '-' to prefix the switch):

-s          Send all queued outgoing SMTP mail
-g          Get mail waiting on the POP3 host
-c          Complete configuration
-m          Minimal configuration (used when calling PMPOP from Pegasus
            Mail, which provides the remaining information itself)
-v          Verbose - report as much information as possible
-q          Quiet - no progress indicator or screen output
-u <name>   Specify the POP3 account name
-p <pwd>    Specify the POP3 account password
-n <"name"> Specify the user's personal (must be quoted)
-a          Force standalone operation
-5 <1|0>    Delete/don't delete downloaded mail on the host
-4 <file>   Search mask (including wildcards) of files PMPOP should
            look for when processing outgoing mail
-3 <path>   DOS Path to directory where incoming mail should be placed
-2 <host>   Address (or domain name) of SMTP relay host
-1 <host>   Address (or domain name) of POP3 mail host


─── About PMPOP ──────────────────────────────────────

PMPOP is written by David Harris and is provided as a free utility in
support of the Pegasus Mail e-mail system. Although it is free, it is NOT
in the public domain, and the author retains all rights to it. Having
said that, you may distribute it freely subject to three conditions: you
may not charge for it; you may not bundle it as part of any other package
without the author's explicit permission; and you may not alter it
in any way.

For LAN Workplace connectivity, PMPOP uses the Novell LAN Workplace
toolkit, a quality library available from your Novell dealer.

For Packet Driver connectivity, PMPOP uses Erick Engelke's excellent
WATTCP TCP/IP stack and library. WATTCP is well-supported, free
software, which can be obtained by anonymous FTP from dorm.rutgers.edu in
/pub/msdos/wattcp/wattcp.zip. WATTCP includes a number of useful TCP/IP
utilities, and the libraries are available in full source form. If you
are interested in developing TCP/IP applications to run in the Packet
Driver environment, I can strongly recommend you look at WATTCP - and
please consider buying the manual too; Erick is very deserving of your
support. NOTE: You do not need to get WATTCP to be able to use PMPOP - it
already has what it needs built in.

To contact PMPOP's author, you can send mail to:

   (Internet)      [e-mail]
   (CompuServe)    >internet:[e-mail]